Unit tests as api usage examples (2010)
Motivation
現代においてプログラムを書くときは大量のAPIを使ってプログラムを記述する
大量のAPIの使い方を学ぶ必要がある
Developers rely on different information sources to learn about APIs.
The standard documentation of the API,
sample code,
online tutorials,
and books are some examples of the supporting resources.
Ideally, a developer would be able to learn how to use the API quickly using the aforementioned supporting materials.
Unfortunately, many APIs lack these artifacts or come with imperfect or low quality content.
Code example は API 理解の良いリソースとなる、Code example を見つけるためには
code search engine を使ってコード検索を行えるが、in-house API には使えないし
creating and maintaining a collection of examples can become undesirable;; it would simply create more development and maintenance effort.
Unit test は良い code example なんじゃないか? なぜなら
changes are going to be applied to the code, its unit tests must also pass
なので code example が outdated なことはない
tanishiking24.icon この論文では述べられていないが
hr.icon
どんなもの?
主張
Qualitative analysis of the experiment results revealed that unit tests are in fact very helpful, especially when the task is complicated and involves multiple classes and methods
hr.icon
先行研究と比べてどこがすごい?
Unit test が code example として優れているという主張は以前からあったが、今研究ではそれを裏付けるための empirical study を行なった
hr.icon
どうやって有効だと検証した?
大学内から1年程度のJavaプログラミング経験があり、Apache POI を使ったこ
ない人たちを募集
16 participants took part in the experiment;; 13 graduate students, 2 senior undergraduate students and one participant from the industry.
実験は2つのフェーズ
The first phase was the initial learning phase in which the subjects were given a short tutorial document, adapted from the HOWTO and the Quick Guide pages of the POI website.
その後で実験参加者は2グループに分けられる
javadoc は見れないけど test case にアクセスできる (test case を参照にしてねって言われた?)
test case が見つかりやすいように、package とかディレクトリ構造を整理してあらかじめ実験参加者に伝えてある
test case は見れないけど javadoc にアクセスできる
それぞれでタスクをやってもらって、タスクの完了度合いを比較する
結果
https://scrapbox.io/files/60d8154c60c490001c0adb80.png
task 1,2,4は単純なタスク、3は結構大変(パターンフォーマティングを設定する)
実験から得られた hypothesis と implication
Hypothesis 1: Examples are crucial in tasks involving complex API usage scenarios. A task of such nature could not be done easily if the only information source available to the developer is the standard Javadoc documentation.
Hypothesis 3: The standard mechanisms provided by the IDE are not enough for finding useful API usage examples.
実験参加者が unit test 見れるグループの人でも、テストがどれか調べるのに苦労していた
Implication: Tool support should be provided to automate the extraction of examples from the unit tests.
Hypothesis 5: Finding relevant examples can help developers correct their wrong perception of the API. Therefore, prevents them from committing numerous errors due to their flawed mental model.
code example を見ると、API usage に対するメンタルモデルを正すことができる
code example は便利だねってこと?
hr.icon
次に読むべき論文は?
investigated problems that developers in Microsoft had in using APIs. He found that the API documentation must include good examples, be complete, and support many complex usage scenarios. Our study provides more evidence for the findings of 5RELOODUG¶VVWXG\
なんか test case が code example として優れているのはわかったけど、test case が github とかに落ちてるコードよりも example として優れていることを示す論文はある?
別にそこ言わなくてもいいかも、なぜなら両立できるから